home *** CD-ROM | disk | FTP | other *** search
/ CD ROM Paradise Collection 4 / CD ROM Paradise Collection 4 1995 Nov.iso / basic / pbasmlib.zip / SOUND.DOC < prev    next >
Text File  |  1994-02-12  |  40KB  |  843 lines
  1. PBASMLIB Soundblaster/Adlib Module
  2. (C) Copyright 1994 by Tim Gerchmez
  3. All Rights Reserved.
  4.  
  5. Soundblaster is a trademark of Creative Labs
  6. Adlib/Ad Lib is a trademark of Ad Lib, Inc.
  7.  
  8. All other software and hardware mentioned herein is owned and
  9. copyrighted by its respective companies.
  10.  
  11. The Sound Module lets you play music, sound effects, digital samples and
  12. synthesized speech from BASIC on the Soundblaster card.  It also lets you
  13. record from the Soundblaster's Microphone or Line Inputs, and play back the
  14. recorded data.  The routines in this module will be immediately accessible
  15. to your PB programs by including the statements $INCLUDE "PBASMLIB.INC" and
  16. $LINK "PBASMLIB.PBL" at the top of your programs.  These routines are usable
  17. with the PC-AT and compatibles or better, and may not work correctly with
  18. the PC-XT.  Many of the routines DO NOT require a driver to be loaded before
  19. using them.  The syntax of each routine is explained in the section below,
  20. after the quick reference section (which follows).
  21.  
  22. Special note: These routines are not compatible with the POW! Soundblaster
  23. library for PowerBASIC, also released by PBASMLIB's author.  If you use
  24. POW! in addition to PBASMLIB, you should remove the SOUND module DECLARE
  25. statements in PBASMLIB.INC, as the POW! library commands are a superset of
  26. the commands available in PBASMLIB's Sound module.
  27.  
  28.  
  29.  PBASMLIB Sound Module Quick Reference
  30.  -------------------------------------
  31.  
  32.  Digitized I/O and Related Routines (internal):
  33.  ----------------------------------------------
  34.  
  35.                  -----------------------------------------------
  36. SBPLAYFILE:      Plays back a file containing raw sample data
  37. SBPLAYSTRING:    Plays back a string containing raw sample data
  38.                  -----------------------------------------------
  39. SBSAMPLE$:       Records a sample from the SB's Line/Mic Inputs
  40.                  into a string
  41. SBSAMPLEBYTE:    Records a single byte from the SB's Line/Mic
  42.                  Inputs
  43.                  -----------------------------------------------
  44.  
  45.                  -----------------------------------------------
  46. SBRESET:         Resets the SB card, preparing for digitized I/O
  47. SBSETBASE:       Sets the base port for the SB card (0220h Default)
  48.                  ------------------------------------------------
  49.  
  50.  
  51.  (2) FM Music (Adlib-Compatible) and related routines (internal):
  52.      ------------------------------------------------------------
  53.  
  54.                    ----------------------------------------
  55. SBFMNOTE:          Plays a note on the Soundblaster
  56. SBFMSOUND:         Plays a sound on the Soundblaster
  57. SBFMRHYTHM:        Plays a rhythm sound on the Soundblaster
  58. SBFMPLAY:          Plays music contained in a string
  59.                    ----------------------------------------
  60. SBFMCLEAR:         Clears the Soundblaster's FM Music Registers
  61. SBFMPARMS:         Sets parameters for the FM Music Channels
  62. SBFMPORTOUT:       Outputs directly to the FM Music Registers
  63. SBFMSETPORTS:      Sets the FM Music Register addresses
  64. SBFMDETECT:        Detects whether an FM Music-Capable (Adlib/SB)
  65.                    card is present
  66.                    -----------------------------------------
  67.  
  68.  
  69.  (3) .CMF FM Music Playback (driver):
  70.      --------------------------------
  71.  
  72.                  ---------------------------------------------
  73. SBCMFDETECT:     Checks if the SBFMDRV.COM driver is loaded
  74. SBCMFPLAY:       Plays a .CMF file in the background (SBFMDRV.COM)
  75. SBCMFTRANSPOSE:  Transpose the pitch of a .CMF file (SBFMDRV.COM)
  76. SBCMFSETSPEED:   Changes speed of default CMF file playback (SBFMDRV.COM)
  77. SBCMFCHECK:      Checks whether a .CMF file is still playing (SBFMDRV.COM)
  78. SBCMFPAUSE:      Pauses playback of a .CMF file (SBFMDRV.COM)
  79. SBCMFRESUME:     Resumes playback of a .CMF file (SBFMDRV.COM)
  80. SBCMFCANCEL:     Cancels playback of a .CMF file (SBFMDRV.COM)
  81.                  ---------------------------------------------
  82.  
  83.  
  84.  (5) Speech Synthesis Routines (driver):
  85.      -----------------------------------
  86.  
  87.                  ----------------------------------------------------------
  88. SBSAY:           Speaks a string through the SB Speech driver (SBTALKER)
  89. SBSPEECH:        Checks to see if the SB Speech driver is loaded (SBTALKER)
  90.                  ----------------------------------------------------------
  91.  
  92.  
  93.  (6) General SB-Related Routines (internal):
  94.      ---------------------------------------
  95.  
  96.                  ---------------------------------------------------------
  97. SBBEEP:          Sounds a beep through the Soundblaster's FM
  98.                  Music Channel
  99. SBDELAY:         Delay specified number of milliseconds (used by SB
  100.                  routines)
  101. SBDETECT:        Detects whether a Soundblaster card is present
  102.                  ---------------------------------------------------------
  103. SBPRESETMIXER:   Resets the Soundblaster Pro card's mixer chip
  104.                  (SOUNDBLASTER PRO ONLY)
  105. SBPSETMIXER:     Sets the Soundblaster Pro's mixer chip settings
  106.                  (SOUNDBLASTER PRO ONLY)
  107.                  ---------------------------------------------------------
  108.  
  109. ================================================================================
  110. sub sbbeep
  111.  
  112. Plays a BEEP through the soundblaster.  This is one of the "highest
  113. level" routines in the Sound module, requiring no parameters at all.
  114. Similar to the BEEP statement, but plays through the SB's speakers
  115. rather than the PC speaker.  You don't even have to detect if an SB
  116. card is present, as SBBEEP does this for you, and plays a normal BEEP
  117. through the PC speaker if not!
  118.  
  119. Example: sbbeep [or] call sbbeep
  120.  
  121. ================================================================================
  122. sub sbcmfcancel
  123.  
  124. Cancels (stops) playback of a .CMF file originally started with
  125. SBCMFPLAY.  You can then use SBCMFPLAY again to restart the song
  126. from the beginning, if desired.
  127.  
  128. Example: call sbcmfcancel
  129.  
  130. ================================================================================
  131. function sbcmfcheck
  132.  
  133. Checks whether a .CMF file is still playing (SBFMDRV.COM),
  134. and returns nonzero if yes, or zero if not.  Use with
  135. SBCMFPLAY to determine status of playing file.
  136.  
  137. Example: print sbcmfcheck
  138.  
  139. ================================================================================
  140. function sbcmfdetect
  141.  
  142. Detects whether the FM Music Driver (SBFMDRV.COM) for the
  143. Soundblaster card is installed.  Returns 0 if not, or IRQ
  144. number (&h80-&hbf) if it is.  You should use this before
  145. calling any of the other SBCMF commands to determine whether
  146. the driver was loaded.
  147.  
  148. Example: print sbcmfdetect
  149.  
  150. ================================================================================
  151. sub sbcmfpause
  152.  
  153. Pauses a currently playing .CMF song (that you started with
  154. SBCMFPLAY).  You can use SBCMFRESUME to continue playback.
  155.  
  156. Example: call sbcmfpause
  157.  
  158. ================================================================================
  159. sub sbcmfplay(f$,ary%(1))
  160.  
  161. Plays a .CMF file in the background, using the SBFMDRV.COM driver.
  162. You should pass this routine a 64K integer array to hold the CMF
  163. music data, and the CMF files you select should be less than 64K
  164. in size.  You do not have to check for the SBFMDRV.COM being installed
  165. if you don't want to ; this routine does it automatically, and will
  166. terminate if the driver is not installed.  If a song is already playing
  167. when this function is called, it will be ended and a new song started.
  168.  
  169. f$: Set to path\filename of .CMF file to play
  170.  
  171. ary%(1): Set to the first element of a 64K integer array
  172.          (see example below).  Array can be shorter than 64K
  173.          if you're sure that the size of the CMF file is less
  174.          (you can open for binary access and use the LOF function
  175.          to determine the length of a file).  If you forget to
  176.          DIMension the array, or DIM it to too small a size, memory
  177.          will be corrupted when the .CMF file loads.
  178.  
  179. Example:  'SBFMDRV.COM should already be loaded (can be loaded high using
  180.           'the DOS 5+ LH or LOADHIGH command.
  181.  
  182.           DIM cmfary%(1:32767) '64K integer array to hold .CMF data
  183.           call sbcmfplay "test.cmf",cmfary%(1)  'Play the file
  184.  
  185. You can use SBCMFCHECK to determine whether the piece is still playing
  186. or has finished (see SBCMFCHECK for details).
  187.  
  188. ================================================================================
  189. sub sbcmfresume
  190.  
  191. Resumes playback of a song after pausing it with the
  192. SBCMFPAUSE command.
  193.  
  194. Example: call sbcmfresume
  195.  
  196. ================================================================================
  197. sub sbcmfsetspeed(s%)
  198.  
  199. Changes the SBFMDRV.COM driver clock rate.  This rate is specified
  200. in each .CMF file, and determines the speed the .CMF file will be
  201. played back.  Using a positive value for this function will increase
  202. the default value read from a file and passed to the CMF driver by the
  203. specified amount, and using a negative value will decrease the default.
  204. This function can either be used with a CURRENTLY PLAYING .CMF file (to
  205. slow it down or speed it up), or can be used before a file is played to
  206. change the speed at which the next file will be played back.  Using a
  207. value of 0 will set the SBFMDRV.COM speed back to the default rates.
  208.  
  209. Example:
  210.          sbcmfsetspeed -8              'Slow down all .CMF files by 8 Cycles
  211.          sbcmfplay "test.cmf",ary%(1)  'Plays back .CMF file slower than normal
  212.          do:loop until sbcmfcheck=0    'Wait til song is over
  213.          sbcmfsetspeed 0               'Returns playback speed to default
  214.  
  215. ================================================================================
  216. sub sbcmftranspose(nm%)
  217.  
  218. Transposes the pitch of a piece of music up or down by
  219. a particular number of half-tone steps.  Use this command
  220. either before playing a .CMF file or during playback to
  221. change the base pitch of the music.
  222.  
  223. nm%: Set to number of half-tone steps to transpose.  A
  224.      positive value will transpose up, while a negative
  225.      value will transpose down.  Using a value of zero
  226.      will turn transposing off and set the tone of the
  227.      music back to the original.
  228.  
  229. Example: sbcmftranspose -4  'Transpose 4 steps down
  230.  
  231. ================================================================================
  232. sub sbdelay(ms%)
  233.  
  234. Pauses the specified number of milliseconds.
  235.  
  236. ms%: Set to milliseconds (thousandths of a second) to pause.
  237.      (0-32767).  Max is about 32 seconds.
  238.  
  239. Example: sbdelay 1000 'Delay one second exactly (hardware-independent).
  240.  
  241. ================================================================================
  242. function sbdetect
  243.  
  244. Detects whether a Soundblaster or compatible card is installed,
  245. and returns -1 if yes or 0 if no.  You should use this routine
  246. before calling any Digital (sampling) I/O functions in this library.
  247. Use SBFMDETECT instead before calling FM Music-related routines, as
  248. the Adlib card will return a not-installed status with this routine
  249. (it's not upward compatible with the Soundblaster).  Note: This
  250. routine also RESETS the SB card, and can be used in lieu of SBRESET
  251. if desired.
  252.  
  253. Example: d% = sbdetect
  254.  
  255. ================================================================================
  256. sub sbfmclear
  257.  
  258. Clears and initializes the soundblaster's FM music registers.
  259. Use this to (1) stop a sound, (2) before playing sounds to clear
  260. previous values.  Returns all internal FM Music settings
  261. to default values.  To reset the soundblaster hardware, use
  262. SBRESET instead (this command just clears the FM Music Adlib-
  263. compatible registers).
  264.  
  265. Example: call sbfmclear
  266.  
  267. ================================================================================
  268. function sbfmdetect
  269.  
  270. Detects if an Adlib/FM Music-Capable card is installed, and returns
  271.  -1 if yes or 0 if no.  This routine will return -1 for the Soundblaster,
  272. as it's fully compatible with the Adlib card.  Call this before calling any
  273. of the other FM-Music related routines to determine if an appropriate sound
  274. card is installed.  Use SBDETECT instead to check for the Soundblaster card
  275. specifically (for digital I/O and related functions).
  276.  
  277. Example: print sbfmdetect
  278.  
  279. ================================================================================
  280. sub sbfmnote (ch%,fr%,oc%,ad%,sr%,wv%,dly%)
  281.  
  282. Play a note on the soundblaster using the specified FM music
  283. channel and the specified values (see below).  This is the
  284. one of the "lower level" FM Music commands in the Sound Module,
  285. and it gives you a lot of control over parameters.  For a higher-
  286. level command that requires less parameters, see SBFMSOUND.
  287.  
  288.  
  289. ch%:  Set to Soundblaster Melody Channel (voice) (1-9).
  290.  
  291. fr%:  Set to frequency (pitch) (0-1023).  The approximate
  292.       frequency values for a scale are:
  293.       C:  345     C#: 366     D: 388     D#: 409     E: 431
  294.       F:  458   F#: 486   G: 515    G#: 545   A: 579
  295.       A#: 614   B:  650   C: 688
  296.  
  297. oc%:  Set to octave (0-7) (Controls pitch)
  298.  
  299. ad%:  Set to Attack/Decay (AD) value:
  300.       Attack: Bits 4-7 (0=slowest) (0-15)
  301.       Decay : Bits 0-3 (0=slowest) (0-15)
  302.       Formula: ad% = 16 * attack + decay
  303.                attack = ad% \ 16
  304.                decay  = ad% and 15
  305.  
  306. sr%:  Set to Sustain/Release (SR) value:
  307.       Sustain: Bits 4-7 (0=loudest) (0-15)
  308.       Release: Bits 0-3 (0=slowest) (0-15)
  309.       Formula: sr% = 16 * sustain + release
  310.                sustain = sr% \ 16
  311.                release = sr% and 15
  312.  
  313. wv%:  Set to waveform (controls sharpness of tone).
  314.       0-3, where 0="softest" and 3="sharpest."
  315.  
  316. dly%: Set to delay value (in milliseconds) (0-32767, or about
  317.       32 seconds max).  For a delay of zero, routine will play
  318.       note and immediately return without "turning note off" -
  319.       this is appropriate for certain AD and SR values (see
  320.       example below).  If a delay is specified, the routine will
  321.       play the note ("key on"), delay the specified time, then
  322.       turn the note off ("key off").
  323.  
  324. Example: sbfmnote 1,345,5,240,4,1,0 'Play a note on the Soundblaster
  325.  
  326. ================================================================================
  327. sub sbfmparms(ch%,am%,vb%,sus%,hm%)
  328.  
  329. Sets extra parameters for a particular SB FM music channel
  330. that will be used with the other SBFM commands (except SBFMPLAY).
  331. This allows you to "fine-tune" the sound of each channel.
  332. These parameters will remain in effect until you do an SBFMCLEAR
  333. or change the soundblaster's registers directly.
  334.  
  335. Note: SBBEEP uses channel 1, and can be a way to quickly test
  336.       new parameter values.  Simply call SBFMPARMS followed by an
  337.       SBBEEP statement to hear the changes.  SBFMCLEAR resets all
  338.       values set by SBFMPARMS.
  339.  
  340. ch%: Set to Soundblaster channel (1-9) to set parameters for
  341. am%: Set to 1 for Amplitude Modulation (tremolo), or 0 for none.
  342.      The default value is 0.
  343. vb%: Set to 1 for Vibrato, or 0 for none.  The default value
  344.      is 0.
  345. sus%: Set to 1 for Note Sustain, or 0 for none.  The default
  346.       is 0 (no sustain, note decays on SR phase).
  347. hm%: Set to 0-15 to control which harmonic the specified channel
  348.      is modulated with.  This controls the overall pitch and
  349.      tinniness of the output for the specified channel.  The
  350.      default for this setting is zero.
  351.  
  352. Example: call sbfmparms(1,0,1,0,0) 'Set vibrato for channel 1
  353.          sbbeep  'Hear the vibrato
  354.  
  355. ================================================================================
  356. sub sbfmplay(m$)
  357.  
  358. Plays music on the Soundblaster - a mini music interpreter, similar
  359. to PB's PLAY command, but works with the soundblaster rather than the
  360. PC speaker, uses different parameters, and is much more flexible.  All
  361. SBFMPLAY commands are 2 characters in length (no exceptions), and these
  362. commands are detailed below.  The string you send is checked for an even
  363. number of characters (as each command is two bytes), and SBFMPLAY terminates
  364. if the string is not an even length.  See the example sound programs
  365. included with PBASMLIB for examples of SBFMPLAY syntax.  When building strings
  366. for SBFMPLAY, it is suggested that you do it in layers - add the notes, rests
  367. and octave notations first, then add the chords and other commands later.
  368.  
  369. m$: Set to a string of characters indicating musical notes and commands
  370.     for SBFMPLAY:
  371.  
  372. a ,a-,a+,b ,b-,b+,c ,c-,c+,d ,d-,d+,e ,e-,e+,f ,f-,f+,g ,g-,g+
  373. A ,A-,A+,B ,B-,B+,C ,C-,C+,D ,D-,D+,E ,E-,E+,F ,F-,F+,G ,G-,G+
  374.  
  375. Musical notes in SBFMPLAY are indicated by the note letter (the regular
  376. scale CDEFGAB), followed by a space (regular note), a minus (flat), or
  377. a plus (sharp).  You can substitute the "b" character for the minus and
  378. the "#" for the plus, if desired.  Each note indicated is ALWAYS two
  379. characters long.  Using LOWERCASE letters for notes will produce a delay
  380. between each note, while using UPPERCASE letters will play a note and
  381. proceed immediately to the next note (useful for polyphonic music).  The
  382. note letters are the only place SBFMPLAY is case-sensitive.  The following
  383. are valid strings of notes:
  384.  
  385. "a a#b b#c c#d d#" <- Notice each note is EXACTLY two characters.  Regular
  386.                       notes (not flat or sharp) can be followed by ANY
  387.                       character, whereas flats are followed by "-" or
  388.                       "b", and sharps are followed by "+" or "#".
  389.  
  390. "C DbE F#G A#B c d e f#g-a+b-c+" <- the first part will be played without
  391.                                     delays between notes.  This string is
  392.                                     read C, D flat, E, F sharp, G, A sharp,
  393.                                     B, C, D, E, F sharp, G flat, A sharp,
  394.                                     B flat, C sharp.
  395.  
  396. See the "O" (Octave) command for further control of note pitch.
  397.  ------------------------------------------------------------------------------------
  398. h0,h1,h2,h3,h4,h5,h6,h7,h8,h9,ha,hb,hc,
  399. hd,he,hf,hg,hh,hi,hj,hk,hl,hm,hn,ho (upper or lowercase):
  400.  
  401. The "h" command plays a CHORD.  All standard 3-voice major and minor
  402. sharp and flat chords are supported in SBFMPLAY.  7th chords and others
  403. are not currently supported.  Voices 4-6 of the Soundblaster are used
  404. for chords, so if you use them, v1-3 and v7-9 are free for the melody
  405. (rhythm uses v7-9 - see the "X" command).  The following "h" (the H may
  406. be capitalized) commands correspond to the following chords:
  407.  
  408. h0: C   h4: G    h8: Dm   hc: Am      hg: F#/Gb     hk: D#m/Ebm
  409. h1: D   h5: A    h9: Em   hd: Bm      hh: G#/Ab     hl: F#m/Gbm
  410. h2: E   h6: B    ha: Fm   he: C#/Db   hi: A#/Bb     hm: G#m/Abm
  411. h3: F   h7: Cm   hb: Gm   hf: D#/Eb   hj: C#m/Dbm   hn: A#m/Bbm
  412.                                                     ho: silence chord
  413.  
  414. All chord commands are two characters, as are all note commands.
  415. To cause chords to sustain, rather than play once, use the "N" command.
  416.  ------------------------------------------------------------------------------------
  417. i0,i1,i2,i3 (upper or lowercase):
  418.  
  419. "I" sets vIbrato (rapid variation of frequency) and tremolo (rapid
  420. variation of volume) on and off.  Use I1 to turn vibrato on for the
  421. current channel (last specified with the V command), I2 to turn
  422. tremolo on, or I3 to turn BOTH vibrato and tremolo on.  I0 will
  423. turn off vibrato and/or tremolo for the current channel.
  424.  ------------------------------------------------------------------------------------
  425. n0,n1,n2,n3,n4,n5,n6,n7,n8,n9 (upper or lowercase):
  426.  
  427. The "N" command controls the eNvelope of the notes in the SBFMPLAY
  428. string.  A sound's envelope consists of its attack, decay, sustain
  429. and release (ADSR) phases, which have to do with the changes in
  430. volume of a note during its lifetime.  The attack rate is how
  431. quickly the sound rises from zero to full volume.  The decay rate
  432. is how fast the note falls off from the attack peak to the sustain
  433. level.  The sustain level is the volume the note sustains at until
  434. it's released.  The release rate is how quickly the note falls off
  435. from the sustain level to zero volume when released.  If all this
  436. is confusing to you, it doesn't matter - the "N" command in SBFMPLAY
  437. lets you choose from some predefined sound envelopes.  N0 - N5 are
  438. NOTE envelopes (affecting the A-G note commands), while N6 - N9 are
  439. CHORD envelopes (affecting the H0-Ho commands).  The following "N"
  440. commands are predefined:
  441.  
  442. n0: Note (default) - fast attack, medium release (string sound)
  443. n1: Note - medium attack, slow release (softer sound)
  444. n2: Note - fast attack, fast release (plink sound)
  445. n3: Note - Medium all (ADSR) (medium sound)
  446. n4: Note - Slow attack, slow release ("backward" or "wah wah" sound)
  447. n5: Note - Slow attack, very slow release (soft sustain)
  448. n6: Chord (default) - fast attack, medium release (string sound)
  449. n7: Chord - slow attack, medium release
  450. n8: Chord - slow attack, slow release
  451. n9: Chord - slow attack, no release (sustain chords)
  452.  
  453. You can use "S" (Sustain notes) in combination with the "N" commands to
  454. fine-tune the envelope of notes.  You can also both N values below 5 and
  455. N values above 5 to set both voice and chord envelopes.  For example,
  456. "n2n8" is a perfectly valid combination.
  457.  ------------------------------------------------------------------------------------
  458. o0,o1,o2,o3,o4,o5,o6,o7 (upper or lowercase):
  459.  
  460. The "O" command changes octaves.  For example, you would insert
  461. "o4" in the command string at the right place to change to octave 4.
  462. All subsequent notes will play in that octave until changed with
  463. another "O" command.  The octave setting defaults to o5.
  464.  -------------------------------------------------------------------------------------
  465. p0,p1,p2,p3,p4,p5,p6,p7,p8,p9 (upper or lowercase):
  466.  
  467. "P" controls the overall pace of the music (or tempo).  The number you
  468. provide is multiplied by 10 and used as a "millisecond base" for delays
  469. in conjunction with the "W" command (described later).  The "P" command
  470. controls the actual wait time of the "W" (wait) command.  P1, for example,
  471. would provide a millisecond delay base of 0,10,20,30,40,50,60,70,80,90
  472. corresponding to W0 through W9. Contrary to what you might imagine, the
  473. larger the number given, the SLOWER the actual pace will be.  The lower
  474. the number, the FASTER the pace.
  475.  -------------------------------------------------------------------------------------
  476. q1,q2,q3,q4,q5,q6,q7,q8,q9 (upper or lowercase):
  477.  
  478. The "Q" command stands for "quiet," and will silence a voice.  This is
  479. useful when used with the "S" (sustain) command, to shut off a voice at
  480. will.  You provide the number of the channel to silence along with the Q.
  481. For example, "q3" would silence voice (channel) 3.
  482.  -------------------------------------------------------------------------------------
  483. r0,r1,r2,r3,r4,r5,r6,r7,r8,r9,r. (upper or lowercase):
  484.  
  485. The "R" command stands for "Rest."  Placing an R in the music string with
  486. a number value will pause for the same amount of time as a corresponding
  487. note would according to the current setting of the "W" command.  R0 will
  488. pause no time at all, and R. (r followed by a dot) will pause the same
  489. amount of time as the notes (a normal full rest).  The actual wait time
  490. of each rest can be controlled by the "P" command the same way the "W"
  491. command is.  You may have to play around to get a feel for the timing of
  492. the "R" command.
  493.  -------------------------------------------------------------------------------------
  494. s0,s1 (upper or lowercase):
  495.  
  496. The "S" command controls note sustain.  When set to one, all voices will
  497. be sustained after they are played.  When set to 0, the voice will play
  498. for a second and then be silenced (like a guitar string).  Simply insert
  499. the Sx command at the desired place in the command string.  Sustain applies
  500. to "regular" notes only - to set chord sustain, use the "N" command (N9) to
  501. set an envelope for chords that supports a sustain effect.  Use the "N" and
  502. the "S" commands together to control the ENVELOPE of the notes played (see
  503. the "N" command for an explanation).  For those who've already read that
  504. section, the "S" command sets the SUSTAIN of notes to high and the RELEASE
  505. value to 0 (no release) if turned on, or 4 (medium release) if turned off.
  506. Using "S" does not affect the attack/decay portion of the note envelope.
  507.  -------------------------------------------------------------------------------------
  508. t0,t1,t2,t3 (upper or lowercase):
  509.  
  510. The "T" command controls the TONE of the music playing.  The higher the
  511. number the "sharper" and more string-instrument like the sound will be.
  512. Number parameters can range from 0 (very soft) to 3 (very sharp).
  513.  --------------------------------------------------------------------------------------
  514. u0,u1,u2 (upper or lowercase):
  515.  
  516. The "U" command stands for User, and determines how the user can cancel
  517. the SBFMPLAY command.  U0 sets SBFMPLAY to cancel when the user presses
  518. any key (this is the default), U1 sets SBFMPLAY so the user can cancel
  519. the command only with the ESC key, and U2 sets SBFMPLAY so the user cannot
  520. cancel it until the string is done playing.  Once again, SBFMPLAY defaults
  521. to allowing the user to cancel by pressing any key on the keyboard (SBFMPLAY
  522. will not cancel in the middle of a rest or other delay, only between notes).
  523.  --------------------------------------------------------------------------------------
  524. v1,v2,v3,v4,v5,v6,v7,v8,v9 (upper or lowercase):
  525.  
  526. "V" controls which voice (channel) of the soundblaster will be used to play all
  527. notes following the command (until the next V command).  Provide a channel
  528. number between 1 and 9.  For example, "v1C v2E v3G " will play 3 notes, each
  529. note on a different soundblaster channel (note the required space after the final
  530. "G" note).
  531.  ---------------------------------------------------------------------------------------
  532. w0,w1,w2,w3,w4,w5,w6,w7,w8,w9 (upper or lowercase):
  533.  
  534. "W" stands for Wait, and controls how long SBFMPLAY will wait after
  535. starting to play a note.  If you set the wait value to zero, it will
  536. immediately continue on to the next note (same as if you used a
  537. capital letter to represent the next note).  The actual time the "W"
  538. command waits is determined by the "P" (pace) command.  Use "W" to
  539. set the overall time between notes, while using "R" to add arbitrary
  540. rests between notes.  The "W" wait value defaults to 5 if never set
  541. in the SBFMPLAY string.
  542.  ----------------------------------------------------------------------------------------
  543. x0,x1,x2,x3,x4,x5,x6,x7,x8,x9 (upper or lowercase):
  544.  
  545. The "X" command plays a drumbeat or rhythm - think of the letter X
  546. as a pair of crossed drumsticks to help you remember this command.
  547. Each command (X0 through X9) plays a different rhythm sound.  Please
  548. listen to these sounds to determine which ones are correct for the
  549. songs you are playing.
  550.  
  551. Example: SBFMPLAY "x3r4x3r4x3r4x3r4" 'Plays 4 drum beats with rests
  552.                                      'between them
  553.  
  554. ================================================================================
  555. sub sbfmportout(rg%,dat%)
  556.  
  557. Lets you write directly to the Soundblaster's FM registers,
  558. should you be so inclined.  A good book on the Soundblaster
  559. (or the SB Developer's kit) is recommended, as an explanation
  560. of Soundblaster registers is beyond the scope of PBASMLIB's documentation.
  561. This command is for the FM music registers only (normally &h388 and &h389);
  562.  
  563. it does not work for digitized sound playback.  You do not have to include
  564. delays, etc. after writing the ports using this command, as they are built
  565. into the SBFMPORTOUT command.
  566.  
  567. rg%: Set to register to write to (01h-F5h)
  568. dat%: Set to data to write to register (0-255)
  569.  
  570. Example: sbfmportout &h60,0 'Set channel 1 Attack/Decay to 0
  571.  
  572. ================================================================================
  573. sub sbfmrhythm(drum%,ad%,sr%,fr%,oc%)
  574.  
  575. Play a rhythm sound on the soundblaster.  FM Melody channels 7-9
  576. are not available when using this command.  You'll have to experiment
  577. to find the appropriate parameters for the different types of drum
  578. sounds.
  579.  
  580. drum%: Set to drum sound desired:
  581.        Bit 0 = Hi Hat (add 1)
  582.        Bit 1 = Snare (add 2)
  583.        Bit 2 = Tom tom (add 4)
  584.        Bit 3 = Cymbal (add 8)
  585.        Bit 4 = Bass (add 16)
  586. ad%:  Set to Attack/Decay (AD) value:
  587.       Attack: Bits 4-7 (0=slowest) (0-15)
  588.       Decay : Bits 0-3 (0=slowest) (0-15)
  589.       Formula: ad% = 16 * attack + decay
  590.                attack = ad% \ 16
  591.                decay  = ad% and 15
  592.  
  593. sr%:  Set to Sustain/Release (SR) value:
  594.       Sustain: Bits 4-7 (0=loudest) (0-15)
  595.       Release: Bits 0-3 (0=slowest) (0-15)
  596.       Formula: sr% = 16 * sustain + release
  597.                sustain = sr% \ 16
  598.                release = sr% and 15
  599. fr%: Set to frequency (0-1023)
  600. oc%: Set to octave (0-7)
  601.  
  602. Example: sbfmrhythm 8,240,4,1000,7 'Play a note on the snare drum
  603.  
  604. ================================================================================
  605. sub sbfmsetports(addr%,dat%)
  606.  
  607. Sets the soundblaster's Address/Status port and
  608. Data port locations.  These are the ports for Adlib
  609. compatible FM Music output.  It's highly unlikely you'll
  610. need to use this function, as the defaults (&h388
  611. and &h389) are standard Soundblaster/Adlib ports, but
  612. it's included for future compatibility, and in case
  613. an unusual hardware setup presents a problem.  See
  614. SBSETBASE for a related function to set the SB base
  615. I/O address for digitized sound output.
  616.  
  617. addr%: Set to SB Address/Status port (normally &h388)
  618. dat%: Set to SB Data port (normally &h389)
  619.  
  620. Example: sbfmsetports &h388,&h389 'Set to default values
  621.  
  622. ================================================================================
  623. sub sbfmsound(ch%,fr%,oc%)
  624.  
  625. Play a note on the Soundblaster using the specified FM sound
  626. channel and the specified values.  This is a mid-level function
  627. that gives you less control over SB FM sound parameters than SBFMNOTE
  628. does, but makes it easier to play a note.  Routine returns immediately
  629. (no delay between notes).  Waveform and ADSR values are preset for
  630. each channel:
  631.  
  632. Ch 1: Soft sound, fast attack, slow release
  633. Ch 2: Medium sound, fast attack, slow release
  634. Ch 3: Sharp sound, fast attack, slow release
  635. Ch 4: Soft sound, medium attack, medium release
  636. Ch 5: Medium sound, medium attack, medium release
  637. Ch 6: Sharp sound, medium attack, medium release
  638. Ch 7: Soft sound, slow attack, slow release
  639. Ch 8: Medium sound, slow attack, slow release
  640. Ch 9: Sharp sound, slow attack, slow release
  641.  
  642. ch%: Set to SB sound channel (1-9)
  643. fr%:  Set to frequency (pitch value) (0-1023).  The
  644.       approximate frequency values for a scale are:
  645.       C:  345     C#: 366     D: 388     D#: 409     E: 431
  646.       F:  458   F#: 486   G: 515    G#: 545   A: 579
  647.       A#: 614   B:  650   C: 688
  648. oc%:  Set to octave (0-7) (Controls pitch)
  649.  
  650. Example: sbfmsound 1,409,5  'Play a "D#" on channel 1 in octave 5
  651.  
  652. ================================================================================
  653. sub sbplayfile (f$,dly%)
  654.  
  655. Plays an uncompressed digitized (raw) sound file through the Soundblaster
  656. in the foreground (processing will not continue until the file is done
  657. playing).  A utility is included with PBASMLIB to convert .VOC and .WAV files
  658. to .RAW files that can be played with this routine (MAKERAW.EXE).
  659.  
  660. NOTE: Use the $STRING metastatement to allocate the maximum size
  661. string segment possible, as the shorter the string, the less of the
  662. file can be read in at once, and the more delays you may hear in the
  663. playback of the file.  $STRING 32 is recommended.
  664.  
  665. f$: Set to the path\filename of the file to play.  You should not
  666.     attempt to play back .VOC and .WAV files directly with this
  667.     routine (convert them to raw sample data with MAKERAW first).
  668.     Although it can be done, it will introduce a lot of extra noise
  669.     into the samples because of the extra information included in .VOC
  670.     and .WAV files (header, block types, etc).
  671.  
  672. dly%: Set to a delay value, which will vary depending on the
  673.       speed the sound file was originally recorded at.  Experiment
  674.       with this value to find the optimal delay setting for the file(s)
  675.       you are playing.  The higher the value given, the slower the file
  676.       will be played back (the longer the delay).
  677.  
  678.  
  679. Example: sbplayfile "test.raw",60  'Play back a .RAW file with delay of 60.
  680.  
  681. ================================================================================
  682. sub sbplaystring(s$,rte%)
  683.  
  684. Plays back a sample recorded into a string with SBSAMPLE$, and
  685. can also play any raw sample data contained in a string.  Similar
  686. to SBPLAYFILE, but plays from a string instead of from a file.
  687.  
  688. s$: Set to string containing digitized sample data retrieved with
  689.     SBSAMPLE$, or from a file containing raw sample data.
  690.  
  691. rte%: Set to playback rate (see SBSAMPLE$ and SBPLAYFILE for examples
  692.       of how the rate value applies to playback speed.
  693.  
  694. Example: s$=sbsample$(8000,40)  'Record a sample
  695.          sbplaystring s$,40     'Play back sample s$ at rate 40
  696.  
  697.  
  698. ================================================================================
  699. sub sbpresetmixer <SB-PRO ONLY>
  700.  
  701. Resets the onboard mixer to power-up state on the Soundblaster
  702. Pro card.  Probably won't do any harm using the mixer commands with
  703. a regular Soundblaster, but the user should be polled in your program
  704. as to the type of SB card he/she has.  See SBPSETMIXER to set the values
  705. of the SB Pro's onboard mixer chip.
  706.  
  707. Example: call sbpresetmixer
  708.  
  709. ================================================================================
  710. sub sbpsetmixer(ms%,mv%,vfm%,vcd%,vln%,vvc%,vmc%) <SB-PRO ONLY>
  711.  
  712. Sets values for the Soundblaster Pro's mixer chip.  Calling this
  713. routine with a regular Soundblaster probably won't do any harm, but
  714. the user should be polled in your program as to the type of SB card he
  715. or she has.  See SBPRESETMIXER to reset the mixer chip to power-up values.
  716.  
  717. ms%: Set to 0 for mono or 1 for stereo output.  This also selects
  718.      filtered output automatically.
  719. mv%: Set to master volume setting (0-15) for left and right channels.
  720.      The formula to use is 16 * left channel + right channel.
  721. vfm%: Set to volume for FM music (0-15) for left and right channels.
  722.       The formula to use is 16 * left channel + right channel.
  723. vcd%: Set to volume for CD output for left and right channels.
  724.       The formula to use is 16 * left channel + right channel.
  725. vln%: Set to volume for line in, left and right channels.
  726.       The formula to use is 16 * left channel + right channel.
  727. vvc%: Set to volume for digitized sound for left and right channels.
  728.       The formula to use is 16 * left channel + right channel.
  729. vmc%: Set to volume for microphone input (0-7).
  730.  
  731. Example: sbpsetmixer 1,255,255,255,255,255,255 'Stereo, max volume all.
  732.  
  733. ================================================================================
  734. sub sbreset
  735.  
  736. Resets the Soundblaster card, preparing it for digitized output.
  737. This is similar to the SBFMCLEAR command (which applies to FM music),
  738. but SBRESET should be called before using SBPLAYFILE, SBPLAYSTRING or
  739. SBSAMPLE$ for the first time.  You should call it once before outputting
  740. digitized sound with any of the above mentioned commands, and again if you
  741. start using a new command at some point in your program.
  742.  
  743. Example: call sbreset
  744.  
  745. ================================================================================
  746. function sbsample$(ln%,rte%)
  747.  
  748. Reads a digital sample from the Soundblaster's Line In or Microphone
  749. Input and stores it in a string.  The sample can then be played back with
  750. SBPLAYSTRING, or stored in a file and played back later with SBPLAYFILE.
  751.  
  752. ln%: Set to length of sample to take.  This value should never exceed
  753. the string segment size set with $STRING (see example below).  The sample
  754. will be read until the entire sample length you passed in ln% is taken.
  755.  
  756. rte%: Set to a RATE value, similar to the dly% parameter in SBPLAYFILE.
  757. The higher the value of rte% you provide, the more recording time you'll
  758. get from a given value passed in ln%, but the poorer the sound quality.
  759. I have gotten good results with rte% values from 10 to 50.  Lower than
  760. 10 will give you very little recording time with few additional benefits,
  761. and the accuracy as related to SBPLAYFILE playback decreases as well (if
  762. you use the same value for rte% in sbsample$ and dly% in sbplayfile).
  763. Values over 50 usually result in poor sound quality.
  764.  
  765. Example: $string 8   'must be 8 or greater for this example
  766.          call sbreset  'Reset the SB
  767.          print "Press a key to start recording a sample";
  768.  
  769.          while inkey$="":wend
  770.          s$ = sbsample$(8000,40)  'Take an 8000-byte sample at rate 40
  771.          open "sample.raw" for output as #1  'Prepare to save the sample
  772.          print #1,s$;                        'Write sample to file
  773.          close #1
  774.          print "Press a key to play the sample back"
  775.          sleep
  776.          sbplayfile "sample.raw",40  'Play back the digital sample.
  777.  
  778. ================================================================================
  779. function sbsamplebyte
  780.  
  781. Allows you to sample a byte directly from the Soundblaster's Microphone
  782. or Line Input, allowing you to signal your program via voice or sound
  783. input.  It also allows experimentation with voice recognition and other
  784. similar ideas.
  785.  
  786. sbsamplebyte: Returns the value of the byte most recently sampled from the
  787.               SB's Line In or Mic In.  This will be 128 for no input, and
  788.               a varying other value depending on the amplitude and the
  789.               waveform of the input signal.  128 seems to be the median
  790.               value, with values dropping below and climbing above this
  791.               number as the waveform of the input signal changes.
  792.  
  793. Example:  call sbreset  ;Always recommended before using sbsamplebyte
  794.           do
  795.              print sbsamplebyte
  796.           loop
  797.  
  798. ================================================================================
  799. sub sbsay(s$)
  800.  
  801. Note: This command will not function in the PB IDE and must be
  802.       run within a standalone .EXE file.
  803.  
  804. Speaks a string as synthesized speech if the SB speech
  805. driver is loaded (check for it with SBSPEECH before calling).
  806. String should be a maximum of 255 characters in length.
  807.  
  808. Example: sbsay "Hello there!"
  809.  
  810. ================================================================================
  811. sub sbsetbase(io%)
  812.  
  813. Sets the base address for the Soundblaster card
  814. (normally &h220).  This controls output of digitized
  815. sounds (SBPLAYFILE/SBPLAYSTRING commands).  To set
  816. the Adlib FM-Music ports, use SBFMSETPORTS instead.
  817.  
  818. Note: You can often get this address from the BLASTER environment
  819.       variable. If you use S$=ENVIRON$("BLASTER"), a string will be
  820.       returned in S$ of the form "A220 I7 D1 T3".  The A220 indicates
  821.       the base address (220 hex), the I7 the interrupt number (7), the D1
  822.       the DMA number (1). The T indicates the type of sound card.  You can
  823.       parse this string out and use SBSETBASE to set the SB's base address
  824.       for the PBASMLIB Sound Module (the interrupt, type and DMA values are
  825.       not needed by this module).
  826.  
  827. io%: Set to base I/O port address for the Soundblaster card.
  828.  
  829. Example: sbsetbase &h220
  830.  
  831. ================================================================================
  832. function sbspeech
  833.  
  834. Note: This command will not function in the PB IDE and must be
  835.       run within a standalone .EXE file.
  836.  
  837. Returns -1 if the SB's speech driver is installed,
  838. or 0 if not.  Use before calling SBSAY to add synthesized
  839. speech to your programs.
  840.  
  841. Example: print spspeech
  842.  
  843.